PIC 16CXX Simulator 1. Simulator Overview 1 2. Commands 3 3. Command Line Options 5 4. Journal file 6 5. Input Stimulus File 7 1. Simulator Overview 1.1. Description PSIM is a versatile software simulator for Microchip PIC16CXX series microcontrollers. It allows the user to simulate their code on a PC to verify its proper operation. 1.2. Requirements PSIM requires an IBM or compatible computer (XT or above) with at least 400K bytes of free memory to run. Although PSIM will function with a monochrome monitor, it is strongly recommended that a VGA monitor be used to take full advantage of the features. 1.3. Syntax PSIM uses the listfile that is produced by various Parallax assemblers (see assembler documentation for producing listfiles). It is also compatible with listfiles produced by Microchip's PICALC and MPALC and the beta version (0.01) of the PIC Macro Assembler by Applied Academics. To start PSIM, type "PSIM filename" at the DOS prompt, where filename is the name of the listfile that you would like to simulate. The file extension ".lst" can be omitted -- the ".lst" extension is assumed by default. If there are no errors, PSIM will load the listfile and display the source code in the lower half of the screen. The microprocessor's internal registers (files) are displayed in the upper half of the screen. The bottom line of the screen lists the function key commands. 1.4. Device Type PSIM determines the device type being simulated (e.g., PIC16C54, 55, 56, 57, 58, 71, 84) by a variety of methods. The recommended method is to include the "device" directive in source code (see assembler instructions for details). The simulator locates the "device" directive in the list file and sets the device type accordingly. If the "device" directive is omitted, the simulator will determine the device type by the type of the list file and the amount of program ROM that is used by the source code. If there are no instructions above address 1FFH hex, the PIC16C54 is assumed. If there are instructions higher than 1FFH but not higher than 3FFH, the PIC16C56 is assumed. If there are instructions above 3FFH than the PIC16C57 is assumed. Another method to select the device type is to include it in the command line preceded by "/d=". Examples are as follows (they are all equivalent): PSIM filename /d=PIC16C54 PSIM filename /d=PIC54 PSIM filename /d=54 The final method for selecting the device type is to use the Alt-D command from within the simulator. Pressing Alt-D will pop up a menu where you can use the up and down arrow keys to select the desired device. Press enter when the desired device is highlighted. Keep in mind that the PIC16C5X and PIC16C71/84 are not object code compatible. If the device is set to PIC16C71 while simulating PIC16C5X code, unexpected results will occur. 1.5. Crystal Frequency The simulator uses a crystal frequency value to calculate the instruction cycle time. The crystal value can be entered by one of two different methods. The first method is to enter it on the command line after the filename preceded by "/x=". Upper or lower case characters are allowed. Allowable suffixes are "MHz", "kHz", and "Hz". If no suffix is entered, it is assumed to be in Hertz (cycles/second). Some examples are as follows: PSIM filename /x=4MHz PSIM filename /x=3.12MHz PSIM filename /x=32.768kHz PSIM filename /x=32768Hz PSIM filename /x=32768 The second method of entering the crystal value is to press Alt-C from within the simulator and type in a new value. See the Alt-C command below for further details. If no crystal frequency is entered, it will default to 8MHz upon startup. 1.6. Scrolling You may scroll through the source code displayed in the lower half of the screen by using the up and down arrow keys, PgUp, PgDn, Home and End. The Home key brings you to the beginning of the address space, while the End key brings you to the end. The marker on the middle line is used for showing the current program counter location and for setting breakpoints. The line indicating the current program counter location is displayed in gray with blue letters. When you press the up or down arrow keys, you can scroll up or down through the code. The line marker is highlighted in black with yellow characters when you scroll off of the current program counter line. To set a breakpoint in your code, you may scroll through the code until the desired line is highlighted at the center, then press F2. This will set a breakpoint at that line and denote this by highlighting it in red. There are no limits to the number of breakpoints that you can set. 1.7. Altering RAM To alter a register (file) during simulation, you may use one of two methods. If your computer has a mouse, you can move the mouse cursor until the desired register is highlighted. Then press the left mouse button to increment the register contents or the right mouse button to decrement it. The upper and lower nibbles of a register can be incremented or decremented separately for those that are displayed in hex. For those that are displayed in binary, you may alter each bit separately. Some of the registers are not allowed to change. You may not change the indirect address register (f0). The indirect address is not physically implemented in the processor and altering it would have no effect. Also, if the selected device is a PIC54 or 55 you may not change the upper two bits of the program counter, since these devices do not implement these bits. For the PIC56, you are not allowed to alter the upper bit of the program counter. If you do not have a mouse, you may select a register by pressing and holding the control key and using the arrow keys to move the highlighted cursor. This highlighted cursor will move from register to register as you press the arrow keys (while the ctrl key is held). When it is on the desired register, you can release the control key and type in the desired value for that register. If you are altering a register that is displayed in hex, you can type in any valid hex character. If you are altering a register that is displayed in binary, you may only type in 1's or 0's. You must type in all the numbers that are highlighted before the new value will be accepted. The highlighted cursor will disappear when you resume simulation. 1.8. Watchdog Timer The watchdog timer may be enabled or disabled using one of two methods. The first is to include the "wdt_on" or "wdt_off" assembler directive in the source code (see assembler documentation for details). The second method is to press Alt-W from within the assembler. A menu will pop up allowing the user to select "enable" or "disable" with the up or down arrow keys. Press return when the proper selection is highlighted. 1.9. Quitting To quit PSIM and return to DOS, press escape (ESC) or Alt-X. You will then be asked to verify your decision before it will quit. Press "y" to quit or "n" or ESC to return to the simulator. 2. Commands The function key commands are as follows: F1 - HELP. This displays the help menu. Use the Page Down key to display the second page of the help menu. F2 - BRKPT. Toggle the breakpoint at the highlighted line. To insert a breakpoint at a specific line, use the cursor keys to scroll the program display up or down until the desired line is displayed in the center highlighted bar, then press F2. The line will then turn red to indicate that the breakpoint is set. Pressing F2 again on the same line will clear the breakpoint. F3 - CLEAR. Clear all breakpoints. F4 - HERE. Execute the code until the highlighted line is reached. Pressing F4 will simulate the program line by line until the center highlighted line is reached. The message "running..." is displayed at the bottom of the screen to indicate that it is simulating. When the highlighted line is reached, the screen is updated and the registers that were altered are highlighted. To stop the simulation while it is running, press any key. F5 - TIME. Reset the real time display to zero. This is useful for timing code execution. F6 - GO. Pressing F6 will start the simulator running, and will not stop until a key is pressed or a breakpoint is reached. The screen is updated and the changes are highlighted after each line is executed. F7 - STEP. This causes one line to be executed. The changes in the registers are highlighted after the line is executed. Pressing the space bar also executes one line. F8 - NEXT. F8 causes the simulator to execute until the next line is reached or a breakpoint is reached. This is useful for executing through subroutine calls. If F8 is pressed when the cursor is on a subroutine call, the simulator will execute the code until the line after the call is reached. The user can also stop execution at any time by pressing any key. If the F8 key is pressed when the highlighted line is at the end of the address space (e.g. 1FFH for the PIC16C54), it will never reach the next line, since it is out of the code space. In this case, it will continue running until the user presses any key to stop it. F9 - RUN. This causes the simulator to execute the code until a breakpoint is reached or any key is pressed. The screen is not updated until execution is stopped. F10 - RESET. This simulates a hardware reset. SPACE - STEP. Same as F7. Alt-C CRYSTAL. The crystal value defaults to 8MHz. This value is used to calculate execution time. To enter a new crystal value, press Alt-C. A window will pop up allowing the user to type in the desired crystal frequency value. The user can type the value in Hertz (Hz), kiloHertz (kHz), or megaHertz (MHz) by typing the value and the appropriate suffix. If no suffix is entered, it is assumed to be in Hertz. The suffix can be upper or lower case or a combination of the two. Some examples are as follows: 32768, 32768Hz, 32.768kHz, 1MHz, 3.57MHz. Alt-D DEVICE. To select a different device type, press Alt- D while in the simulator. This will pop up a menu where you can use the up and down arrow keys to select the desired device. Press enter when the desired device is highlighted. You must be careful when using this method. Any code that is above the address limit of the newly selected device will be eliminated. Also, keep in mind that the PIC16C5X and PIC16C71/84 are not object code compatible. If the device is set to PIC16C71 while simulating PIC16C5X code, unexpected results will occur. To exit from the device menu without changing the device type, press escape. Alt-E DISPLAY EEPROM. If the device is set to PIC16C84, the user can view the contents of the EEPROM data memory by pressing Alt-E. This is not available when any other processor type is selected. Alt-F LOAD FILE. To load in a different file, press Alt-F. A file menu will pop up allowing the user to select a file from the list. The list files are displayed in yellow and directories are in red. Only files with a '.lst' extension are listed. To load a file, use the cursor keys to move the highlighted cursor to the desired file and press enter. If you need to load a file from a different directory, move the highlighted cursor to the desired directory and press enter. The display will then list the files in the selected directory for you to choose from. To quit the file menu without loading in a new file, press the escape key. Alt-S DISPLAY STACK. The first two stack locations are displayed at the top left side of the screen at all times. If the device type is set to PIC16C71 or PIC16C84, the user can display all 8 stack locations in a pop up window by pressing Alt-S. Alt-W WATCH DOG TIMER. To enable or disable the watch dog timer, press Alt-W from within the assembler. A menu will pop up allowing the user to select "enable" or "disable" with the up or down arrow keys. Press return when the proper selection is highlighted. Alt-F4 JUMP TO CURSOR. Moving the cursor to a new line and pressing Alt-F4 causes the simulator to jump to the highlighted line, without executing any instructions. This is useful for jumping directly to code segments that you wish to debug, without having to run through the normal code execution to get there. It is also useful for jumping over long delay loops in your code. Alt-F7 BACK STEP. Pressing Alt-F7 steps backward one line in your program. The entire state of the microcontroller is stored in a 100 element history buffer to allow the user to step back through the code up to 100 steps. Alt-X EXIT. Pressing Alt-X exits the simulator and returns to DOS. A pop-up prompt will allow you to confirm the exit command. 3. Command Line Options Valid command line options are as follows: /d=device, where device = pic54, pic55, pic56, pic57, pic58, pic71, or pic84. This sets the type of processor being simulated, overriding the normal listfile device detection. /e- -disables serial port checking for the in-circuit emulator. Normally, PSIM checks the available serial ports for the presence of the in-circuit emulator. If you are not using the emulator and do not want PSIM to alter your serial ports, you can disable it with this command line option. /e=n -where n is the number of the serial port connected to the in-circuit emulator. This forces PSIM to only look for the emulator on the specified com port at startup. /f- -disables serial port checking for the I/O simulator Reflection 5X. Normally, PSIM checks the available serial ports for the I/O simulator. If you are not using Reflection 5X and do not want PSIM to alter your serial ports, you can disable it with this command line option. /f=n -where n is the number of the serial port connected to the I/O simulator Reflection 5X. This forces PSIM to only look for Reflection 5X on the specified com port at startup. /i=filename -where filename is the input stimulus file name. This loads the stimulus file for execution during simulation. See section 5 for details. /j=journalfile -where journalfile is the journal file name. This loads and executes the keystrokes read from the journal file. See section 4 for details. /j- -shut off journal file feature. Keystrokes will not be stored in the journal file. /r -randomizes RAM values on startup. By adding the command line parameter /r, the file registers will come up in a random state, with the exception of the RAM locations 2 through 7 (or 2 through 6 for the PIC57). This more accurately simulates an actual PIC microcontroller, since it's RAM comes up in random states upon power up. /s -disable stack overflow and underflow error detection. /x=xtal, where xtal = crystal frequency. This sets the crystal frequency used by the simulator to calculate instruction cycle time. /? -display help menu showing valid command line options. 4. Journal Files All keystrokes entered during simulation are automatically stored in a journal file named 'psim.jrn' in the current default directory. This file is automatically created during each PSIM session, unless it is turned off with the command line option: "/j-". When you re-enter PSIM, the last journal file will be overwritten. If you want to retain the journal file for later use, rename it or copy it to another filename before re-executing PSIM. To re-run a journal file, type: "psim listfile /j=journalfile" at the DOS prompt. This will load in the listfile and execute the keystrokes read from the journalfile. This feature is useful for configuring your simulation session upon startup. For instance, you can initialize an I/O port to a certain value or set some breakpoints in your code. This setup can then be automatically executed upon startup of later simulation sessions. Note that mouse movements and mouse button clicks are not stored in the journal file -- you must use the cursor keys for initializing register values. 5. Input Stimulus File The stimulus file feature allows the user to schedule bit changes in the I/O port pins at specified times during simulation. This scheduling is controlled via a text file called a stimulus file. The "/i=filename" command line option is used to read in the stimulus file, where "filename" is the name of the stimulus text file. The stimulus file is an ASCII file containing instructions for applying stimuli to the I/O pins of the microprocessor. All commands must be comma separated. White spaces and tabs are ignored. Any line beginning with a semicolon is a comment line. There are five different schedule commands to tell when you want the stimulus applied to the I/O pin(s). These commands must be the first command on a line. The five commands are t=r, c=n, dt=r, dc=n, and pc=n, where r is a real number and n is an integer. The t=r command applies the stimulus when the time reaches r. The c=n command applies the stimulus when the cycle counter reaches n. The dt and dc commands apply the stimuli when the delta time (or delta cycles) reach the given value. That is, when that command is reached, the current time (or cycle count) is read, and the delta time (or delta cycle count) is added to the reading to give the stimulus time. After the schedule command comes the stimulus command. The stimulus on each line can be applied to one I/O pin (e.g. ra0=1) or to a full port (e.g. rb=d5h). It can also be applied to the RTCC pin (e.g. rtcc=0) or, when simulating a PIC16C71, can be applied to the analog inputs of the A/D converter (e.g. ain2=4.80v). You may have up to 8 I/O bit changes per line or 3 full port changes. The following are examples of valid stimulus commands: ; This is a comment line in the stimulus file pc=8, ra=2dh,rb=feh ; this sets port A to 2d hex, and ; port B to fe hex when the program ; counter reaches 8 (program counter ; values are entered in decimal, port ; values in hex). t=0.00002, ra0=1, ra3=0 ; this sets bit 1 of port A and ; clears bit 3 of port A at ; time = 0.00002 seconds c=50, rb0=1 ; this sets bit 0 of port B after ; the 50th cycle is reached dt=0.00001, rb7=1 ; this sets bit 7 of port B when ; dt=0.00001 seconds. In this example ; it will occur 0.00001 seconds after ; the 50th cycle. dc=12, rtcc=1 ; sets the RTCC pin 12 cycles after : the last stimulus dc=5, rtcc=0 ; clears the RTCC 5 cycles after ; the last stimulus.